jsdom-global

What is jsdom-global?

The jsdom-global npm package is used to set up a global DOM environment in Node.js, which is particularly useful for testing and running scripts that are designed to work in a browser environment. It leverages the jsdom library to create a simulated DOM, allowing developers to run browser-specific code in a Node.js environment.

What are jsdom-global's main functionalities?

Global DOM Setup

This feature sets up a global DOM environment by requiring the jsdom-global package. The code sample demonstrates how to initialize the global DOM and log the document object to the console.

require('jsdom-global')();
console.log(window.document);

Simulating Browser APIs

This feature allows you to simulate browser-specific APIs like `alert`. The code sample shows how to override the `alert` function to log messages to the console instead.

require('jsdom-global')();
window.alert = (msg) => console.log(`Alert: ${msg}`);
window.alert('Hello, world!');

Testing with Mocha

This feature is useful for setting up a DOM environment for testing purposes. The code sample demonstrates how to use jsdom-global with the Mocha testing framework and Chai assertion library to test DOM manipulation.

const jsdomGlobal = require('jsdom-global');
const { expect } = require('chai');

jsdomGlobal();
describe('DOM Manipulation', () => {
  it('should create a new div element', () => {
    const div = document.createElement('div');
    document.body.appendChild(div);
    expect(document.body.contains(div)).to.be.true;
  });
});

Other packages similar to jsdom-global

jsdom

The jsdom package is the underlying library that jsdom-global uses to create a simulated DOM environment. While jsdom-global sets up a global environment automatically, jsdom requires more manual setup but offers more control and customization options.

happy-dom

Happy DOM is another package that provides a DOM-like environment for Node.js. It is designed to be lightweight and fast, making it a good alternative to jsdom-global for performance-critical applications.

linkedom

LinkeDOM is a minimalistic and fast DOM implementation for Node.js. It aims to be a lightweight alternative to jsdom, providing essential DOM functionalities with a focus on performance.

README

jsdom-global

Enables DOM in Node.js

jsdom-global will inject document, window and other DOM API into your Node.js environment. Useful for running, in Node.js, tests that are made for browsers.

Install

Requires jsdom.

npm install --save-dev --save-exact jsdom jsdom-global

Note

jsdom-global now requires jsdom v10 or above. If you need jsdom v9 and below, use the previous version (jsdom-global@2).

Usage

Just invoke it to turn your Node.js environment into a DOM environment.

require('jsdom-global')()

// you can now use the DOM
document.body.innerHTML = 'hello'

You may also pass parameters to jsdomGlobal() like so: require('jsdom-global')(html, options). Check the jsdom.jsdom() documentation for valid values for the options parameter.

To clean up after itself, just invoke the function it returns.

var cleanup = require('jsdom-global')()

// do things

cleanup()

Tape

In tape, run it before your other tests.

require('jsdom-global')()

test('your tests', (t) => {
  /* and so on... */
})

Mocha

Simple: Use Mocha's --require option. Add this to the test/mocha.opts file (create it if it doesn't exist)

-r jsdom-global/register

Advanced: For finer control, you can instead add it via mocha's before and after hooks.

before(function () {
  this.jsdom = require('jsdom-global')()
})

after(function () {
  this.jsdom()
})

ES2015

If you prefer to use import rather than require, you might want to use jsdom-global/register instead. Place it on top of your other import calls.

import 'jsdom-global/register'
import React from 'react'
import jQuery from 'jquery'
// ...

Browserify

If you use Browserify on your tests (eg: smokestack, tape-run, budo, hihat, zuul, and so on), doing require('jsdom-global')() is a noop. In practice, this means you can use jsdom-global even if your tests are powered by browserify, and your test will now work in both the browser and Node.

• Writing your tests (test.js):

  require('jsdom-global')()
  
  // ...do your tests here
  

• Running it with smokestack:

  browserify test.js | smokestack          # run in a browser
  node test.js                             # or the console
  browserify test.js --no-bundle-external  # also works (but why bother?)
  

• Running it with Babel (babelify or babel-cli):

  browserify test.js -t babelify | smokestack  # run in a browser (with babel)
  babel-node test.js                           # or the console
  

Thanks

jsdom-global © 2016+, Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors (list).

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz

Changelog

[v3.0.2]

May 8, 2017

• [#17] - Fix issue with Image. ([@jtag05])
• [#16] - Mark jsdom as a peer dependency. ([@Cinematique])